createPaymentRequest

language

The language in which the payment form is displayed. For more information about supported language codes, see Supported languages. If the language parameter is not set, the language is derived from the browser's Accept-Language HTTP header field. If none of the browser languages are supported, the default is English, en. If the language you set is not supported, an error is returned.

[a-z]{2}

This is a one-dimensional associative array, where you can put any value that you would like to associate with the payment in the call to createPaymentRequest.

Array

Maximum 50 entries of maximum 255 characters each.

type

This is the authorization type. For more information, see Payment request types:

• payment (default)
• paymentAndCapture
• verifyCard
• credit
• subscription
• subscriptionAndCharge
• subscriptionAndReserve

string

ccToken

This is the credit card token value. By using a credit card token from a previous payment, your customer won't have to enter credit card details again. To enable this, select the Enable credit card token check box under Home > Terminal Settings in the Merchant Interface.

[0-9a-f]{41}

sale_reconciliation_identifier

This is the sales reconciliation identifier, used in the reconciliation CSV files you can download from the Merchant Information Interface, or by using the getCustomReport method. For more information, see getCustomReport.This parameter can only be used when the type parameter is set to paymentAndCapture.

String{0,100}

sale_invoice_number

This is the invoice number for the capture.

String{0,100}

ccToken / credit_card_token

This is the credit card token from a previous payment, if this is supplied in the createPaymentRequest then the credit card will be pre-filed out with the card number and expiration month and year. ccToken and credit_card_token can both be used.

String{0,100}

fraud_service

Setting the fraud_service parameter lets you select a different fraud detection service on the payment level.

none

maxmind

red

test

cookie

This is the cookie that will be sent back to all your callback URLs. For example, if your cookie parameters are set to PHPSESSID=id1337;mycookie=mycookievalue;, the cookie header in the callback is Cookie: PHPSESSID=asdfasdfdf23; mycookie=mycookievalue

String

payment_source

This identifies the source of the payment.

Currently we're supporting the following sources:

The default value is eCommerce.

Only eCommerce, mobi, moto, mail_order, telephone_order can be sent by the merchants in the PaymentSource. The rest of the values will be changed inside the gateway internally, as the transaction is being processed

eCommerce

mobi

moto

mail_order

telephone_order

shipping_method

Fraud detection services can use this parameter in the fraud detection calculations.

LowCost

DesignatedByCustomer

International

Military

NextDay

Other

StorePickup

TwoDayService

ThreeDayService

customer_created_date

This is the date when the customer account was first created in your shopping system. Fraud detection services use this parameter in the fraud detection calculations.

Date (yyyy-mm-dd)

organisation_number

this is the company registration number (CRN), and is used to identify the company and verify the fact that it is a entity registered with the relevant authority, for example, Companies House in the UK. Do not confuse this with the customer_info[vat_id], although in some countries the number may be the same.

To ensure that the organisation number field is pre-populated on the invoice payment form, set the organisation_number parameter.

String{0,20}

account_offer

If you set account_offer to required, the customer must have an account set up to be able to use invoice payment.

To disable the account for a specific customer, set account_offer to disabled.

required

disabled

This is the id of the setup agreement payment.

This should be provided only in case of charging verify card agreement.

This is the type of the agreement.

In case the reservation type parameter is subscription, subscriptionAndCharge or subscriptionAndReserve and no agreement[type] is provided, it will create a recurring agreement.

Possible values:

• recurring (Notes: Strong Customer Authentication takes place.)
• instalment (Notes: Strong Customer Authentication takes place.)
• unscheduled (Notes: Strong Customer Authentication takes place.)

This is the type of the unscheduled agreement.

In case the reservation type parameter is subscriptionAndCharge or subscriptionAndReserve and the agreement[type]=unscheduled, the agreement[unscheduled_type] parameter is mandatory.

Possible values:

• incremental (Notes: No cardholder authentication required)
• resubmission (Notes: No cardholder authentication required)
• delayedCharges (Notes: No cardholder authentication required)
• reauthorisation (Notes: No cardholder authentication required)
• noShow (Notes: No cardholder authentication required)
• charge (Notes: Strong Customer Authentication takes place.)

It is a integer value representing the frequency between the charge agreement requests made by the merchant. Possible values: 0 - Flexible; 1 - Daily; 7 - Weekly; 14 - Biweekly; 30 - Monthly; 90 - Quarterly; 365 - Yearly.

Values shown in bold above are supported by all payment methods supporting recurring agreements. Klarna is limited to these 4 only.

Default Value: Monthly for recurring/instalment. Not allowed for unscheduled agreement.

This is a link to a page on the merchant side where the customer can manage the agreement.

This is the exemption type to use when doing the transaction authentication.

Possible values:

• TRA

This is the type of the exemption to use when making the transaction authentication.

Possible values:

• Enabled
• Enforced

We'll do a direct authorization when Enforced value is provided. Nonetheless, we'll do the authentication in case of a soft decline.

The customer's e-user name or user id. This uniquely identifies the user in your system.

The customer's cardholder name.

ltd - limited company

plc - public limited company

public_institution - public institution

Other - all other company types

The last name for the customer's shipping address.

The first name for the customer's shipping address.

The postal code of the customer's shipping address.

The region of the customer's shipping address.

The country of the customer's shipping address as a 2 character ISO-3166 country code.

The city of the customer's shipping address.

The customer's email address. It is required for 3DS to provide a valid email address, which then increases the chances for a frictionless flow, and therefore conversion. If provided will auto-fill the Email input for credit card forms. Please ensure you populate this field to improve the user experience.

The customer's telephone number, without spaces. This must include the country code. You can prefix the code with + (e.g. +446721846), or 00 (e.g. 00446721846), or omit the prefix (e.g. 446721846).

The birth date of the customer

Mandatory if your MCC code is 6012.

The last name for the customer's billing address.

Mandatory if your MCC code is 6012.

The first name for the customer's billing address.

The street address of the customer's billing address.

The city of the customer's billing address.

Mandatory for fraud detection.

The region of the customer's billing address.

Mandatory for fraud detection.

The postal code of the customer's billing address.

Mandatory if your MCC code is 6012.

Mandatory for fraud detection.

The country of the customer's billing address as a 2 character ISO-3166 country code. Northern Ireland is an exception; see here.

Mandatory for fraud detection.

The phone number of the bank where the credit card was issued.

The name of the bank where the credit card was issued.

Certain invoice payment providers require gender to be sent. Use this field to comply with that requirement.

If this parameter is required by the provider, but not set in the method call, the customer is asked for this information on the payment page (callback_form).

A unique identifier of the customers session (eg. an md5 hash of the real session id). Used for fraud detection.

The language setting of the customers browser. Used for fraud detection.

The customers browser identification. Used for fraud detection.

description

Description of an item. This value is going to be used as Plan Description when initiating an agreement on MobilePay Subscriptions.

String (255)

itemId

The item identification. This value is going to be used as the Plan when initiating an agreement on MobilePay Subscriptions.

String (100)

quantity

The quantity of the item. The value must be greater than zero.

It is recommended to use the value 1 when the goodsType parameter is set to subscription_model.

Decimal

unitPrice

The unit price, excluding sales tax. The value must be greater than zero.

unitPrice supports up to three decimals, however for most acquirers and currencies two decimals are recommended.

For Klarna only 2 decimals are supported.

It is recommended to use the same value as the one set on the amount parameter or 0 when setting up an unscheduled agreement.

Decimal

taxPercent

This is the tax percentage of the unit price.

Decimal

taxAmount

This is the total tax on an order line, before any discounts are applied. It is recommended to use taxAmount if possible. If you provide both taxPercent and taxAmount, the amount takes precedence.

Decimal

unitCode

The relevant measurement unit for the order line. For example, kg.

String (50)

discount

The order line's discount in percent. Must be a non-negative decimal number if provided. Will be used to calculate final amount for order line after applying taxes.

Decimal

The goods type of the order line -

The used value must be subscription_model for setting up subscriptions on MobilePay Subscriptions, see MobilePay Agreements
It is recommended use the first element of the orderLines array for agreement setup: orderLines[0][goodsType] = subscription_model.

* Specific to Klarna and PayPal payments

** Specific to Klarna payments

*** Specific to MobilePay, PayPal and Klarna subscriptions

imageUrl

The full URL of the icon for the item

String (255)

travel[fromDate]

The first date of the trip.

Date String yyyy-MM-dd (ex. 2024-05-29)

travel[toDate]

The last date of the trip.

Date String yyyy-MM-dd (ex. 2024-05-29)

As Swish only allows one open payment at a time, the callback_fail form for Swish could offer some explanation, such as "The customer may have an open payment" or "The customer should check their Swish app for open payments".

For Klarna payments, the open page (callback_open) is used for pending transactions.

For Klarna payments, the notification page (callback_notification) is used for transactions pending clarification.

This URL is called just before the payment is processed.

• To return a value that is not part of the normal POST parameters, you can prepend GET parameters to the URL.
• To allow the payment to proceed, you must return a HTTP response with code 200, and a HTML/TEXT response with the value "OKAY". Anything else results in an error message, and an aborted/declined transaction.

If the payment fails, the first 255 characters of your response is shown as an error message to the customer.

This url is called whenever the customer is redirected to a third party, and corresponds to the Callback url (redirect) setting in Terminal settings. For more information, see Settings for the redirect page (callback_redirect).